home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kactioncollection.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  13.1 KB  |  394 lines
  1. /* This file is part of the KDE libraries
  2.     Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org>
  3.               (C) 1999 Simon Hausmann <hausmann@kde.org>
  4.               (C) 2000 Nicolas Hadacek <haadcek@kde.org>
  5.               (C) 2000 Kurt Granroth <granroth@kde.org>
  6.               (C) 2000 Michael Koch <koch@kde.org>
  7.               (C) 2001 Holger Freyther <freyther@kde.org>
  8.               (C) 2002 Ellis Whitehead <ellis@kde.org>
  9.  
  10.     This library is free software; you can redistribute it and/or
  11.     modify it under the terms of the GNU Library General Public
  12.     License version 2 as published by the Free Software Foundation.
  13.  
  14.     This library is distributed in the hope that it will be useful,
  15.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  16.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17.     Library General Public License for more details.
  18.  
  19.     You should have received a copy of the GNU Library General Public License
  20.     along with this library; see the file COPYING.LIB.  If not, write to
  21.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  22.     Boston, MA 02110-1301, USA.
  23. */
  24.  
  25. #ifndef __kactioncollection_h__
  26. #define __kactioncollection_h__
  27.  
  28. #include <kaction.h>
  29.  
  30. #include <qkeysequence.h>
  31. #include <qobject.h>
  32. #include <qvaluelist.h>
  33. #include <qguardedptr.h>
  34. #include <kguiitem.h>
  35. #include <kshortcut.h>
  36. #include <kstdaction.h>
  37. #include <kicontheme.h>
  38.  
  39. class QMenuBar;
  40. class QPopupMenu;
  41. class QComboBox;
  42. class QPoint;
  43. class QIconSet;
  44. class QString;
  45. class KToolBar;
  46.  
  47. class KAccel;
  48. class KAccelActions;
  49. class KConfig;
  50. class KConfigBase;
  51. class KURL;
  52. class KInstance;
  53. class KToolBar;
  54. class KActionCollection;
  55. class KPopupMenu;
  56. class KMainWindow;
  57. class KXMLGUIClient;
  58.  
  59. typedef QValueList<KAction *> KActionPtrList;
  60.  
  61. /**
  62.  * A managed set of KAction objects.
  63.  * 
  64.  * If you set the tooltips on KActions and want the tooltip to show in statusbar
  65.  * (recommended) then you will need to connect a couple of the actionclass signals
  66.  * to the toolbar.
  67.  * The easiest way of doing this is in your KMainWindow subclass, where you create
  68.  * a statusbar, do:
  69.  *
  70.  * \code
  71.  * actionCollection()->setHighlightingEnabled(true);  
  72.  * connect(actionCollection(), SIGNAL( actionStatusText( const QString & ) ),
  73.  *           statusBar(), SLOT( message( const QString & ) ) );
  74.  * connect(actionCollection(), SIGNAL( clearStatusText() ),
  75.  *           statusBar(), SLOT( clear() ) );
  76.  * \endcode
  77.  */
  78. class KDEUI_EXPORT KActionCollection : public QObject
  79. {
  80.   friend class KAction;
  81.   friend class KXMLGUIClient;
  82.  
  83.   Q_OBJECT
  84.  
  85. public:
  86.   KActionCollection( QWidget *parent, const char *name = 0, KInstance *instance = 0 );
  87.   /**
  88.    * Use this constructor if you want the collection's actions to restrict
  89.    * their accelerator keys to @p watch rather than the @p parent.  If
  90.    * you don't require shortcuts, you can pass a null to the @p watch parameter.
  91.    */
  92.   KActionCollection( QWidget *watch, QObject* parent, const char *name = 0, KInstance *instance = 0 );
  93. #ifndef KDE_NO_COMPAT
  94.   KActionCollection( const KActionCollection © );
  95. #endif
  96.   virtual ~KActionCollection();
  97.  
  98.   /**
  99.    * This sets the widget to which the keyboard shortcuts should be attached.
  100.    * You only need to call this if a null pointer was passed in the constructor.
  101.    */
  102.   virtual void setWidget( QWidget *widget );
  103.  
  104.   /**
  105.    * This indicates whether new actions which are created in this collection
  106.    * should have their keyboard shortcuts automatically connected on
  107.    * construction.  Set to 'false' if you will be loading XML-based settings.
  108.    * This is automatically done by KParts.  The default is 'true'.
  109.    * @see isAutoConnectShortcuts()
  110.    */
  111.   void setAutoConnectShortcuts( bool );
  112.  
  113.   /**
  114.    * This indicates whether new actions which are created in this collection
  115.    * have their keyboard shortcuts automatically connected on
  116.    * construction.
  117.    * @see setAutoConnectShortcuts()
  118.    */
  119.   bool isAutoConnectShortcuts();
  120.  
  121.   /**
  122.    * This sets the default shortcut scope for new actions created in this
  123.    * collection.  The default is ScopeUnspecified.  Ideally the default
  124.    * would have been ScopeWidget, but that would cause some backwards
  125.    * compatibility problems.
  126.    */
  127.   //void setDefaultScope( KAction::Scope );
  128.  
  129.   /**
  130.    * Doc/View model.  This lets you add the action collection of a document
  131.    * to a view's action collection.
  132.    */
  133.   bool addDocCollection( KActionCollection* pDoc );
  134.  
  135.   /** Returns the number of widgets which this collection is associated with. */
  136.   //uint widgetCount() const;
  137.  
  138.   /**
  139.    * Returns true if the collection has its own KAccel object.  This will be
  140.    * the case if it was constructed with a valid widget ptr or if setWidget()
  141.    * was called.
  142.    */
  143.   //bool ownsKAccel() const;
  144.  
  145.   /** @deprecated  Deprecated because of ambiguous name.  Use kaccel() */
  146.   virtual KAccel* accel() KDE_DEPRECATED;
  147.   /** @deprecated  Deprecated because of ambiguous name.  Use kaccel() */
  148.   virtual const KAccel* accel() const KDE_DEPRECATED;
  149.  
  150.   /** Returns the KAccel object of the most recently set widget. */
  151.   KAccel* kaccel();
  152.   /** Returns the KAccel object of the most recently set widget. Const version for convenience. */
  153.   const KAccel* kaccel() const;
  154.  
  155.   /** @internal, for KAction::kaccelCurrent() */
  156.   KAccel* builderKAccel() const;
  157.   /** Returns the KAccel object associated with widget #. */
  158.   //KAccel* widgetKAccel( uint i );
  159.   //const KAccel* widgetKAccel( uint i ) const;
  160.  
  161.   /** Returns the number of actions in the collection */
  162.   virtual uint count() const;
  163.   bool isEmpty() const { return (count() == 0); }
  164.   /**
  165.    * Return the KAction* at position "index" in the action collection.
  166.    * @see count()
  167.    */
  168.   virtual KAction* action( int index ) const;
  169.   /**
  170.    * Find an action (optionally, of a given subclass of KAction) in the action collection.
  171.    * @param name Name of the KAction.
  172.    * @param classname Name of the KAction subclass.
  173.    * @return A pointer to the first KAction in the collection which matches the parameters or
  174.    * null if nothing matches.
  175.    */
  176.   virtual KAction* action( const char* name, const char* classname = 0 ) const;
  177.  
  178.   /** Returns a list of all the groups of all the KActions in this action collection.
  179.    * @see KAction::group()
  180.    * @see KAction::setGroup()
  181.    */
  182.   virtual QStringList groups() const;
  183.   /**
  184.    * Returns the list of actions in a particular group managed by this action collection.
  185.    * @param group The name of the group.
  186.    */
  187.   virtual KActionPtrList actions( const QString& group ) const;
  188.   /** Returns the list of actions managed by this action collection. */
  189.   virtual KActionPtrList actions() const;
  190.  
  191.   /**
  192.    * Used for reading shortcut configuration from a non-XML rc file.
  193.    */
  194.   bool readShortcutSettings( const QString& sConfigGroup = QString::null, KConfigBase* pConfig = 0 );
  195.   /**
  196.    * Used for writing shortcut configuration to a non-XML rc file.
  197.    */
  198.   bool writeShortcutSettings( const QString& sConfigGroup = QString::null, KConfigBase* pConfig = 0 ) const;
  199.  
  200.   void setInstance( KInstance *instance );
  201.   /** The instance with which this class is associated. */
  202.   KInstance *instance() const;
  203.  
  204.   /**
  205.    * @deprecated
  206.    */
  207.   void setXMLFile( const QString& );
  208.   /**
  209.    * @deprecated
  210.    */
  211.   const QString& xmlFile() const;
  212.  
  213.   //TODO FOR KDE4 make this default true
  214.   /**
  215.    * Enable highlighting notification for specific KActions.
  216.    * This is false by default, so, by default, the highlighting
  217.    * signals will not be emitted.
  218.    * 
  219.    * @see connectHighlight()
  220.    * @see disconnectHighlight()
  221.    * @see actionHighlighted()
  222.    * @see actionHighlighted()
  223.    * @see highlightingEnabled()
  224.    */
  225.   void setHighlightingEnabled( bool enable );
  226.   /**
  227.    * Return whether highlighting notifications are enabled.
  228.    * @see connectHighlight()
  229.    * @see disconnectHighlight()
  230.    * @see actionHighlighted()
  231.    * @see setHighlightingEnabled()
  232.    * @see actionHighlighted()
  233.    */
  234.   bool highlightingEnabled() const;
  235.  
  236.   /**
  237.    * Call this function if you want to receive a signal whenever a KAction is highlighted in a menu or a toolbar.
  238.    * This is only needed if you do not add this action to this container.
  239.    * You will generally not need to call this function.
  240.    * 
  241.    * @param container A container in which the KAction is plugged (must inherit QPopupMenu or KToolBar)
  242.    * @param action The action you are interested in
  243.    * @see disconnectHighlight()
  244.    * @see actionHighlighted()
  245.    * @see setHighlightingEnabled()
  246.    * @see highlightingEnabled()
  247.    * @see actionHighlighted()
  248.    */
  249.   void connectHighlight( QWidget *container, KAction *action );
  250.   /**
  251.    * Disconnect highlight notifications for a particular pair of contianer and action.
  252.    * This is only needed if you do not add this action to this container.
  253.    * You will generally not need to call this function.
  254.    * 
  255.    * @param container A container in which the KAction is plugged (must inherit QPopupMenu or KToolBar)
  256.    * @param action The action you are interested in
  257.    * @see connectHighlight()
  258.    * @see actionHighlighted()
  259.    * @see setHighlightingEnabled()
  260.    * @see highlightingEnabled()
  261.    * @see actionHighlighted()
  262.    */
  263.   void disconnectHighlight( QWidget *container, KAction *action );
  264.  
  265.   /**
  266.    * The parent KXMLGUIClient, return 0L if not available.
  267.    */
  268.   const KXMLGUIClient *parentGUIClient() const;
  269.  
  270. signals:
  271.   void inserted( KAction* );
  272.   void removed( KAction* );
  273.  
  274.   /** Emitted when @p action is highlighted.
  275.    *  This is only emitted if you have setHighlightingEnabled()
  276.    * @see connectHighlight()
  277.    * @see disconnectHighlight()
  278.    * @see actionHighlighted()
  279.    * @see setHighlightingEnabled()
  280.    * @see highlightingEnabled()
  281.    */
  282.   void actionHighlighted( KAction *action );
  283.   /** Emitted when @p action is highlighed or loses highlighting.
  284.    *  This is only emitted if you have setHighlightingEnabled()
  285.    * @see connectHighlight()
  286.    * @see disconnectHighlight()
  287.    * @see actionHighlighted()
  288.    * @see setHighlightingEnabled()
  289.    * @see highlightingEnabled()
  290.    */
  291.   void actionHighlighted( KAction *action, bool highlight );
  292.   /** Emitted when an action is highlighted, with text
  293.    *  being the tooltip for the action.
  294.    *  This is only emitted if you have setHighlightingEnabled()
  295.    *  
  296.    *  This is useful to connect to KStatusBar::message().  See
  297.    *  this class overview for more information.
  298.    *  
  299.    * @see setHighlightingEnabled()
  300.    */
  301.   void actionStatusText( const QString &text );
  302.   /** Emitted when an action loses highlighting.
  303.    *  This is only emitted if you have setHighlightingEnabled()
  304.    *  
  305.    * @see setHighlightingEnabled()
  306.    */
  307.   void clearStatusText();
  308.  
  309. private:
  310.   /**
  311.    * @internal Only to be called by KXMLGUIFactory::addClient().
  312.    * When actions are being connected, KAction needs to know what
  313.    * widget it should connect widget-scope actions to, and what
  314.    * main window it should connect
  315.    */
  316.   void beginXMLPlug( QWidget *widget );
  317.   void endXMLPlug();
  318.   /** @internal.  Only to be called by KXMLGUIFactory::removeClient() */
  319.   void prepareXMLUnplug();
  320.   void unplugShortcuts( KAccel* kaccel );
  321.  
  322.   void _clear();
  323.   void _insert( KAction* );
  324.   void _remove( KAction* );
  325.   KAction* _take( KAction* );
  326.  
  327. private slots:
  328.    void slotMenuItemHighlighted( int id );
  329.    void slotToolBarButtonHighlighted( int id, bool highlight );
  330.    void slotMenuAboutToHide();
  331.    void slotDestroyed();
  332.  
  333. private:
  334.    KAction *findAction( QWidget *container, int id );
  335.  
  336. #ifndef KDE_NO_COMPAT
  337. public:
  338.   KActionCollection( QObject *parent, const char *name = 0, KInstance *instance = 0 );
  339. #endif
  340.  
  341. public:
  342.   /**
  343.    * Add an action to the collection.
  344.    * Generally you don't have to call this. The action inserts itself automatically
  345.    * into its parent collection. This can be useful however for a short-lived
  346.    * collection (e.g. for a popupmenu, where the signals from the collection are needed too).
  347.    * (don't forget that in the simple case, a list of actions should be a simple KActionPtrList).
  348.    * If you manually insert actions into a 2nd collection, don't forget to take them out
  349.    * again before destroying the collection.
  350.    * @param action The KAction to add.
  351.    */
  352.   void insert( KAction* action);
  353.  
  354.   /**
  355.    * Removes an action from the collection and deletes it.
  356.    * Since the KAction destructor removes the action from the collection, you generally
  357.    * don't have to call this.
  358.    * @param action The KAction to remove.
  359.    */
  360.   void remove( KAction* action );
  361.  
  362.   /**
  363.    * Removes an action from the collection.
  364.    * Since the KAction destructor removes the action from the collection, you generally
  365.    * don't have to call this.
  366.    * @return NULL if not found else returns action.
  367.    * @param action the KAction to remove.
  368.    */
  369.   KAction* take( KAction* action );
  370.  
  371. #ifndef KDE_NO_COMPAT
  372.   KActionCollection operator+ ( const KActionCollection& ) const;
  373.   KActionCollection& operator= ( const KActionCollection& );
  374.   KActionCollection& operator+= ( const KActionCollection& );
  375. #endif // !KDE_NO_COMPAT
  376.  
  377.   // KDE4: clear() doesn't need to be a slot
  378. public slots:
  379.   /**
  380.    * Clears the entire actionCollection, deleting all actions.
  381.    * @see remove
  382.    */
  383.   void clear();
  384.  
  385. protected:
  386.     virtual void virtual_hook( int id, void* data );
  387. private:
  388.     KActionCollection( const char* name, const KXMLGUIClient* parent );
  389.     class KActionCollectionPrivate;
  390.     KActionCollectionPrivate *d;
  391. };
  392.  
  393. #endif
  394.